ParcelAddress API
Get Address Detail - addressid
Resource URL
UAT:
https://api.uat.nzpost.co.nz/parceladdress/2.0/domestic/addresses/{address_id}
Production:
https://api.nzpost.co.nz/parceladdress/2.0/domestic/addresses/{address_id}
Resource Description
Returns the detailed information for a single domestic address identifier.
Resource Information
Attribute | Detail |
---|---|
Response Format | JSON |
Requires Authentication | Yes |
Rate Limited | 15 calls per second. If rate limit is exceeded, calls will be queued. Calls unprocessed for over 60 seconds will time out. |
Please note that all request parameters should be in lower case.
Request Parameters
Field Name | Description | Mand | Example |
---|---|---|---|
address_id | NZ Post address identifier | Yes | 216250 |
Sample Request
https://api.nzpost.co.nz/parceladdress/2.0/domestic/addresses/12345
Response Parameters
The following lists the required fields in the Get Address Detail response message:
Field Name | Description | Mand | Example |
---|---|---|---|
Success | Returns if request is successful | Yes | True |
Address | Address object with address details | Y if success = true | "address": {} |
Address Object
The following lists the required fields in the address object.
Field Name | Description | Mand | Example |
---|---|---|---|
building_name | The name of the building | No | Sky Tower |
company_name | The name of the company associated with the address (rarely available) | No | Acme Inventions |
depot_name | The name of the depot that services this address | No | Akl City Fleet |
floor | The floor number (if it exists) | No | 3 |
latitude | The GPS latitude coordinate if the data exists | Yes | -45.9041 |
longitude | The GPS longitude coordinate if the data exists | Yes | 170.552 |
postcode | The postcode associated with the address | Yes | 2013 |
is_rural_delivery | Determines if this is a rural or a urban address (true for rural) | Yes | True |
rural_delivery_number | The rural delivery number associated with the address | Yes If Rural Delivery = True | 2 |
run_number | The run number that indicates which courier run will service this address | No | DCP003 |
gated_community_flag | Indication that address is within a gated community | No | True |
street | The name of the street | Yes | Highbrook |
street_alpha | The street address alphabetic code indicating multiple delivery locations at the street number eg 25a Main Street. The "a" is the alpha. | No | a |
street_number | The street address number | Yes | 22 |
street_type | Type of street | Yes | Avenue |
suburb | The name of the suburb the address resides | Yes | Pakuranga |
street suffix | Example is 151 victoria street west | Yes | West |
city | The city the address resides in | Yes | Auckland |
unit_type | The unit type of the address | No | Flat |
unit_value | The unit value of the address | No | 27 |
country | The name of the country the address resides | Yes | New Zealand |
dpid | Delivery point identifier | No | 54218 |
Error Response Elements
Field Name | Description | Mand | Example |
---|---|---|---|
success | Returns if request is successful | Yes | false |
errors | Error object with error details | Y if success =false | See Error Object Parameters below |
message_id | The unique message identifier | Yes | ec608f40-2a8b-11e5-a9c0-025c481d35ef |
Error Object Parameters
Field Name | Description | Example |
---|---|---|
code | Error code where first 3 digits are http status code, last three digits identify error type | 400002 |
message | Description of error code | Invalid Parameter(s) |
details | Description of specific error | No results returned. Check your Address ID and try again. |
HTTP Status Codes
Note that some error messages are customised for the request, i.e. error code 400 usually will describe what is wrong with the request
Code | Message |
---|---|
200 | Success |
400 | Bad request |
401 | Unauthorized |
403 | Forbidden |
409 | Invalid request |
500 | System unavailable |
Error Codes
Code | Message |
---|---|
200001 | Partial results returned, not all system(s) have responded |
200002 | All sources responded, data may be incomplete |
400001 | Parameter(s) missing |
400002 | Invalid parameter(s) |
400003 | Non mutually exclusive parameters detected |
401001 | Unauthorised access, please contact administrator |
500001 | General Exception |
500002 | System(s) offline |
Sample Response
Sample success response:
{
"success": true,
"address": {
"street_number": 71,
"street": "Oregon",
"street_type": "Street",
"suburb": "Ocean Grove",
"city": "Dunedin",
"is_rural_delivery": false,
"postcode": "9013",
"longitude": 170.552,
"latitude": -45.9041,
"run_number": "DCP025 ",
"depot_name": "Dunedin Depot",
"country": "New Zealand",
"dpid": "54218",
},
"message_id": "618a5799-85e3-4559-8a62-280f231a26b3"
}
Sample failure response:
{
"success": true,
"errors": [ {
"code": "400002",
"message": "Invalid parameter(s)",
"details": "No results returned. Check your Address ID and try again. "
}],
"message_id": "e5d56f1c-d6f7-4742-a7f8-c411fdb6cae5"
}